@shopify/react-hydrate
![npm bundle size (minified + gzip)](https://img.shields.io/bundlephobia/minzip/@shopify/react-hydrate.svg)
Utilities for hydrating server-rendered React apps.
Installation
$ yarn add @shopify/react-hydrate
Usage
This library is intended to assist with "progressive hydration", a pattern where you fully render an application on the server, but wait to hydrate parts of it when it reaches the client. Typically, doing different work on the server and client would result in the server markup being thrown out by React’s initial reconciliation.
This library avoids that issue by rendering a wrapping div
around the content on the server, adding an ID to that element, and setting the dangerouslySetInnerHTML
prop on the client to the resulting server markup in order to avoid mismatches. Once you have done whatever work on the client to load the necessary components, this hardcoded markup is removed, allowing the React tree to take over.
Server
There are two key pieces to making this work. First, your server must render a HydrationContext.Provider
element around your React tree. This element will provide a HydrationManager
to the tree, which manages the identifiers that map server markup to client markup.
import React from 'react';
import {render} from 'react-dom';
import {HydrationContext, HydrationManager} from '@shopify/react-hydrate';
import App from '../app';
export async function middleware(ctx, next) {
const hydrationManager = new HydrationManager();
ctx.body = render(
<HydrationContext.Provider value={hydrationManager}>
<App />
</HydrationContext.Provider>,
);
await next();
}
Note that if you use @shopify/react-effect
, you must reset the manager after each rendering pass. If you don’t, the identifiers will continue to increment during each pass, and will not match between client and server. You must also use a new HydrationManager
for every request to prevent identifiers leaking between different renders.
import React from 'react';
import {render} from '@shopify/react-html/server';
import {extract} from '@shopify/react-effect';
import {HydrationContext, HydrationManager} from '@shopify/react-hydrate';
import App from '../app';
export async function middleware(ctx, next) {
const hydrationManager = new HydrationManager();
const app = <App />;
await extract(app, {
decorate(element) {
return (
<HydrationContext.Provider value={hydrationManager}>
{element}
</HydrationContext.Provider>
);
},
afterEachPass() {
hydrationManager.reset();
},
});
ctx.body = render(
<HydrationContext.Provider value={hydrationManager}>
<App />
</HydrationContext.Provider>,
);
await next();
}
Application
Once the server is in place, you can start to use the Hydrator
component. This component will do different things depending on its children:
- If children are passed (the server-side case), render those children normally, but inside of a
div
with an identifier that can be matched on the client. - If children are not passed (the client-side case, because this is only used in cases where you will not have the code available to you on the client to render the same markup that was present on the server), render a
div
with dangerouslySetInnerHTML
set to be the HTML of the original, server-rendered markup.
Note: you probably don’t need to know the internals of how progressive hydration works, unless you’re really interested. This package will primarily be used by other tools that manage asynchronous component loading, such as @shopify/react-async
.
import React, {useState, useEffect} from 'react';
import {Hydrator} from '@shopify/react-hydrate';
function MyComponent() {
const [ProgressivelyHydratedComponent, setComponent] = useState(() =>
tryToAccessModuleSynchronously(),
);
useEffect(() => {
let mounted = true;
(async () => {
const Component = await loadModuleAsynchronously();
if (mounted) {
setComponent(Component);
}
})();
return () => {
mounted = false;
};
}, []);
return ProgressivelyHydratedComponent ? (
<Hydrator>
<ProgressivelyHydratedComponent />
</Hydrator>
) : (
<Hydrator />
);
}
You can optionally pass an id
prop to Hydrator
, which will be used to prefix the identifier used to match server and client markup.